Skip to main content

Merchant Payment Solution

When the payment method is ONLINE, the responsibility of collecting payment from the customer lies with the merchant partner. 1MG treats the merchant partner as a payment gateway for such orders.

To enable a smooth order placement and cancellation flow, 1MG requires the following three APIs from merchant partners: one API for payment transactions and two APIs for handling refunds in case of cancellations (full or partial).

API Requirements Overview​

Merchant Team Responsibilities:​

  1. Decide API Endpoints: The merchant team is responsible for deciding the API endpoints.
  2. Response Handling: Provide sample response payloads for non-200 responses for all APIs.
  3. Authentication: Determine the authentication mechanism. If using a token-based mechanism, share the auth-token that should be included in the request headers.
info

1MG always treats Merchant Order Id (merchant_order_id) as the transaction Id.

Merchant Transaction Status API​

This GET API is used to fetch the status of a transaction at any point in the order life cycle. 1MG uses this API to confirm the payment status during the Confirm Order API call. It can also be used to initiate refunds for orders where the order couldn't be confirmed even though the customer was charged.

  • Endpoint: /transactions/{transaction_id}

  • Method: GET

  • URL Parameters: transaction_id: The transaction ID received in the payment initiation call.

Response (200 OK Case):

{
    "order_id": "1MG121211111",
    "transaction_id": "MERCHANT122334444",
    "amount": 1221.11,
    "status": "SUCCESS"
}

Request & Response Parameters Explained:

  • order_id: The 1MG order ID associated with the merchant transaction.

  • transaction_id: The merchant order ID, sent as a URL parameter in this API call.

  • amount: The transaction amount, rounded to two decimal places.

  • status: Enum with values (SUCCESS, PENDING, FAILED). The merchant team can add or update more statuses if they exist.

Merchant Refund Transaction API​

This POST API is used to initiate refunds (both partial and full) in case of cancellations. The refund API must support multiple refund attempts until the sum of all refunded amounts exceeds the total transaction amount.

  • Endpoint: /transactions/{transaction_id}/refunds

  • Method: POST

  • URL Parameters: transaction_id: The transaction ID of the transaction being refunded.

Request Payload:

{
    "order_id": "1MG121211111",
    "amount": 121.11,
    "unique_reference": "1MG121211111-refund-attempt-1"
}

Response (200 OK):

{
    "order_id": "1MG121211111",
    "transaction_id": "MERCHANT122334444",
    "refund_id": "MERCHANT-REFUND-1321211",
    "amount": 121.11,
    "status": "SUCCESS",
    "unique_reference": "1MG121211111-refund-attempt-1"
}

Request & Response Parameters Explained:

  • order_id: The 1MG order ID associated with the merchant order.

  • amount: The amount to be refunded in this API call. It must be less than or equal to the total payment amount minus any amount already refunded.

  • transaction_id: The merchant transaction ID of the transaction being refunded.

  • unique_reference: A unique key sent with this refund attempt. An error should be raised if a refund attempt is made with an existing unique_reference.

  • refund_id: The refund ID generated at the merchant’s end for this refund attempt.

Merchant Refund Status API​

This GET API tracks the status of a refund request initiated using the “Merchant Refund Transaction API” call. This API allows 1MG to check the current status of a refund attempt using the unique_reference passed during the refund initiation.

  • Endpoint: /transactions/{transaction_id}/refunds/status

  • Method: GET

  • URL Parameters: transaction_id: The transaction ID of the transaction for this refund attempt.

Request Payload:

{
    "unique_reference": "1MG121211111-refund-attempt-1"
}

Response (200 OK Case):

{
    "order_id": "1MG121211111",
    "transaction_id": "MERCHANT122334444",
    "refund_id": "MERCHANT-REFUND-1321211"
    "amount": 1221.11,
    "status": "SUCCESS",
    "unique_reference": "1MG121211111-refund-attempt-1"
}

Request & Response Parameters Explained -

  • order_id: The 1MG order ID associated with the merchant order.

  • amount: The refund amount.

  • transaction_id: The merchant transaction ID of the transaction.

  • unique_reference: The unique_reference for this refund from 1MG.

  • refund_id: The refund ID generated at the merchant’s end for this refund attempt.